================================================================================

	  	Bugs and Bug-reports

Please send details of any problems you have with any packages or with Alpha 
itself to the person responsible, or enquire on the Alpha-D mailing list.  
Perhaps someone there will be able to help you out.  Serious bugs which, for 
example, crash Alpha can probably only be fixed by Pete Keleher, but other 
bugs may be Tcl code bugs, and can be fixed more quickly and easily.  
Without a 'Stack Trace' it is ALMOST ALWAYS NOT POSSIBLE to track down 
problems in Alpha's Tcl code, unless they lead to very 'visual' problems.

The help below tells you how to get a stack trace under the most 
general circumstances.  One quick trick you may try is the following.  
Open a Tcl shell (cmd-Y in the file menu) and then repeat the action 
which caused the problem.  Some internal problems are trapped by Alpha 
and errors dumped to the shell window if it's open.  If you're lucky, 
your bug is trapped like that you'll have the trace to report 
automatically.

	  	 Stack-traces

It would be helpful to have a stack-trace if a command is obviously doing
the wrong thing/failing with an error.  To do this, hit cmd-Y to pull up 
the Tcl shell, and select 'Trace Tcl Proc' from the menu.  Select the
procedure you need to trace (or ask me which one to trace), and go back to 
where you were to repeat the action which caused the problem.  Now hit 
cmd-Y again, and then select 'Dump Traces' and mail me the resulting window
which is opened.  

With some errors it may be worth rebuilding your Tcl indices and then 
quitting and restarting Alpha (use the Tcl menu to do that).

Please include the version numbers of Alpha and other packages which you are 
using.  If they are not the latest you should consider upgrading first too.

Sometimes you can get a first estimate at what went wrong by examining 
the 'errorInfo' variable which Tcl sets.  If an action you perform fails, 
hit 'cmd-Y' to bring up the Tcl shell, and then type 'set errorInfo' and 
<return>.  The value of the errorInfo variable will be dumped into the 
shell window.  It may help you to debug things.

	  	 What procedure to trace?

If a menu-selection causes a problem, then it is pretty clear what to
trace, but if it was a key-press it is less clear.
		
Often you won't know which procedure you should trace.  However if the 
problem occurs with a key-press (say you press 'return' and the wrong thing 
happens), then you can find out which procedure is being activated with the 
'Describe Binding (F7)' menu item: hit F7, followed by the offending 
key-press.  Alpha will give you the name of the procedure which would be 
triggered by that key.  Now setup a trace on that procedure as detailed in 
the preceding paragraph.

	  	 Using Trace-func

5.0 introduces the Tcl function-tracing command 'traceFunc'. traceFunc 
allows you to trace a specfic function whenever it is called, sending the 
output to another window. The indented trace of the function includes all 
parameters, each argument enclosed within single quotes, as well as the 
function result. 

The syntax of the function is:

	traceFunc on <funcName> <winName>
	traceFunc off
	traceFunc status

For example, if I want to trace the proc 'nextFunc' (defined in 
procs.tcl), the following might be a log of my activity at the Tcl shell:

	Welcome to Alpha's Tcl shell.
	Alpha> traceFunc on nextFunc traceWin
	Alpha> traceFunc status
	Func-tracing on, func: nextFunc, win: traceWin
	Alpha> 

Now I create a new window, "dirty" it so that I can get a save dialog, 
and save it as 'traceWin'. Note that tracing is only sent to open 
windows, so I must leave 'traceWin' open.

Then I open any random non-C file (because I want the function to fail), go 
to the beginning of the file, and type escape-x 'nextFunc'.  The output 
should look something like the following:

	nextFunc 
	 searchFunc '1' 
	  getPos 
	  OK: 38530
	  select '38530' 
	  OK: 
	  saveVars 
	  OK: 
	  if '(1==1)' '
			nextLine
		' 'else' '
			previousLine
		' 
	   nextLine 
	   OK: 
	  OK: 
	  getPos 
	  OK: 38573
	  set 'pos' '38573' 
	  OK: 38573
	  setVar 'regExpr' '1' 
	  OK: 
	  setVar 'forward' '1' 
	  OK: 
	  setVar 'ignoreCase' '1' 
	  OK: 
	  search '^[^ \t\(#\r/@].*\(.*\)$' '38573' 
	  ERROR: Search unsuccessful
	 ERROR: Search unsuccessful
	ERROR: Search unsuccessful


The trace output shows that the problem was an unsuccessful search. In 
this case, a dialog informed us of this fact anyway, but many Alpha 
routines are not as friendly when it comes to error messages.


Another way to debug Tcl routines is to insert statements that print 
values to another window. For example, one could use the following 
routine: 

	proc out args {
		insertText -w "*tcl shell*" $args
	}

Whatever you do, don't use 'puts stdout' or 'puts stderr' since these
tend to crash Alpha (hopefully to be fixed at some point...)

================================================================================

	  	 Here's some debugging advice from Tom:

Hi All,

This is so simple that I hesitate to admit that I missed it this long, but
I'll swallow my pride an mention this in case anyone  else has missed this.

When you want to get a handle on what a proc is doing, you can use a
combination of the source in one window and the shell in another.

First, figure out what values the parameters of the proc would take on in
the case you want to investigate, (perhaps from a trace while running
things normally).

Now go to the shell and set variables with the same names as the parameters
to the values you discovered through the trace.

Now go to the tcl source file and select a subset of the proc's internal 
code and just load it.

After each sucessive part is run you can pop over to the shell and use it
to check out the state of any variable with a simple set statement, or, 
even easier, just cmd-dbl-click or a variable name you want to inspect the 
value of.

I've found this real useful for investigating menu routines, you can change
the menu creation string that the proc gave you and just select and reload
it to see if your changes will do what you want.

Tom

===============================================================================

	  	Known Bugs

(As of Alpha 7.2)

These are all bugs with Alpha's internal compiled code, _not_ with the 
Tcl scripts which come with Alpha.  You will have to work around them 
where possible.  

()	Dead-key followed by delete removes several characters.

()	When saving large files, the window sometimes goes blank.  Cmd-L
	brings the text back again (it's a visual problem only)

()	under  MacOS 8, sometimes when Alpha is already running and you 
	double click on a file in the finder to open Alpha, you can get
	an error -917 (in the finder) and the file isn't opened.  I think
	OS 8 sends a different aevent to an application of it is already
	running, and this may be the problem.
	
()	If I hit the key equivalent of a menu-item, it is called even if the
	menu item has been disabled.  (This is a MacOS problem and will probably
	never be fixed in Alpha)
	
()	Multi-line edit boxes in dialogs should allow 'return' to be pressed,
	without triggering the 'OK' button.  Otherwise there is no way to enter
	a return.  (sure you can enter '\r' and have the calling procedure
	manipulate the result, but that's not a good solution; also the above
	is standard MacOS behaviour).
	
()	gotoTMark often scrolls the window all the way to the top (0), 
	before scrolling back to a TMark!  This gives the window a 
	horrible up/down jerk motion when moving from one TMark to the 
	next.

()	'replaceText' on a large block of text which overlaps the top of 
	the window (i.e.  half a big paragraph is off the top of the 
	window, half is still visible, and we now replace the paragraph 
	with some different text) causes a re-draw error in which the 
	replacement text is all drawn in the window (from the top down) 
	when only some of it should be visible.  This gives the illusion of 
	over-writing other stuff in the window.  All is ok if you scroll up 
	and down to refresh.

    This is most often manifested when using 'fillParagraph' on a large 
	paragraph which overlaps the top of the window.
	
()	I tried out Adobe Type Reunion Deluxe 2.0 the other day, and it thinks 
	the 'modes menu' towards the right end of the status bar is a font 
	menu!  Most peculiar.

()  Several people have reported these two problems, but not everyone
	sees them:
	
	>Just a quick note...  I am using 7.0b2 on my 9500/132 and 8100/100AV.  On
	>my 8100, the tear-off menus are chopped off on the right side when you tear
	>them off to stand alone.  This happens on a friend's 8100/80 as well.
	>
	
	I'm using Alpha 6.52 on a Starmax 4100 with 7.6.1 and Aaron and I
	experience the same menu tear-off problem.  I also experienced it with 6.5
	and 6.51 (I think).
	
===============================================================================

	  	Pseudo-Bugs

These are things which Alpha perhaps ought to do, but doesn't and hence
can be considered suggestions for the future or just bugs.

()	There's no way to know which application it was which replied to an
	event which was passed to 'handleReply'.
	
()	The colours Alpha uses are incorrect for 'yellow' and 'cyan'.  You can
	fix them if you want using 'config->redefine colors'.

()	Have a flag to allow reporting of errors which hit the top level.  
	Currently such errors just vanish and you're left wondering what exactly 
	did/didn't happen.  I.e. the user should be able to define a 'errorHook'
	procedure which is called with such top-level errors.  (This is 
	effectively the 'bgerror' feature of Tcl 8)

()	If you use 'killWindow' from within an 'openHook' proc, Alpha will
	often crash (MacsBug tells you it's in 'rowColToPos' or some such proc).
	There's no way to abort the open window from within that proc that
	seems to be entirely safe.
	
()	There is currently no facility to get a list of eventHandlers which 
	have been defined.

()	Extend 'matchIt' to cope with '/* ...  */' pairs as well as normal 
	braces.

()	Make 'quick find' and 'reverse quick find' more powerful as follows - 
	'delete' removes one character from what's currently being found (and 
	goes back to where that was found, so it's a kind of 'Undo' feature).  
	Also clicking in the scrollbar, or anything which doesn't actually 
	affect the window shouldn't reset the quick search which it currently 
	does.  Both of these are features in Emacs which I miss in Alpha (as 
	opposed to the other way round which is true of most things).

()	Implement find/replace in the current selection (there is a proc 
	to do this in "procs.tcl", but far more convenient would be a check box 
	in the standard find dialog box).

()	Move the replace-in-fileset facility to the standard find dialog as 
	another option.  In fact why not combine this with the above 
	suggestion and have a pop-up option menu with 'search this document' 
	'search current selection' 'search entire fileset' as options, instead 
	of the current 'multiple files' checkbox?  'Replace All' should replace 
	all occurrences in the current selection/file, whilst for filesets this 
	is rather drastic so I'd suggest there be another checkbox, which says 
	'replace in all files' and changes the meaning of opt-cmd-R in that 
	case.

()	Let a window scroll at least so that the end of the document is 
	half-way up the window?  Currently the last line of text must lie at 
	the very bottom of the window and this is disconcerting when typing a 
	long latex file (one can of course just add a whole bunch of returns, 
	but that shouldn't be necessary).

()	When Alpha's memory is low, put up a warning dialog that you should quit
	and restart.
	
()	'getModifiers' opened up some new possibilities for interface routines, 
	however, in a couple of places where I would like to use this, things 
	are done directly with alpha and there are no Tcl proc's that we can 
	hang modifications off of.  Specifically, neither of the function 
	pop-up's allow you to dectect if a modifier key was held down, (you 
	could then offer a different menu, say the structual marks vs.  the 
	alphabetical mark recently introduced via toTclMarkFile).  Once a menu 
	is presented, there is no way to detect that a choice has been made 
	with a modifier key depressed, this would be useful to provide an 
	automatic mark stack push (such a mechanism does work in the status 
	line <mode> pop-up, if an option key is held while selecting an item 
	there, the help file (if any exists) for that mode will be opened.
	
()	It would be nice if matchIt could put on a little bit more of a display so 
	you are better able to pick it up with your peripheral vission as you are 
	typing. Maybe "halo' the matchIt position before flashing the character, 
	or form a cross of hilited char positions (above and below, both sides) 
	before flashing the matchIt character.
	
	
	  	Fixed but not released.

Things which have been fixed in Alpha 8.0 (release date unknown)

()  'eval ... $args' where the last elment of args was
    something like "} " converts the trailing space into a backslash.
	This is a bug in Tcl 7.5, which has since been fixed.

()	If we have a menu item with a key-equivalent and a mark-charcter, 
	like this: "!/=<Ineq", the 'item' sent to the menu proc is
	not 'neq' as it should be, but rather '!neq'.  This is a bug.
	
()	Cursor-key-bindings can't appear in menus.  More precisely the glyphs
    for the arrow keys can appear, but the menu doesn't create the
    appropriate binding for the keys, so the shortcut doesn't function.
    A workaround is to define 'Bind ...' statements in addition to the
    menu, but this is a bug.
	
()  the GetTMarks list doesn't contain the duplicate window markers
	<2>, <3> etc, as returned by [winNames -f].  This could be considered
	a bug or a feature. 

()	GetTMarks thinks non-file windows are in the '[pwd]' directory,
	rather than in no directory at all.

()	You can't make a menu with both menu-form-conversion and not, unless
	you build it with 'addMenuItem ?-m?', but then you can't add dynamic
	items or sub-menus.  What is needed is a code, like '&', to go in
	the 'menu' command which says "don't convert this item".

()  Error replies to 'dosc' are not always handled correctly:

	Welcome to Alpha's Tcl shell.
	Alpha  dosc -c 'WIsH' -s "file asfasf"
	Error: Error: 1
	Alpha  dosc -c 'WIsH' -s "info asfasf"
	Error: Error: bad option "asfasf": must be args, body, cmdcount, commands, 
	complete, default, exists, globals, hostname, level, library, loaded, locals, 
	nameofexecutable, patchlevel, procs, script, sharedlibextension, tclversion, 
	or vars
	Alpha  
		
	One might think this was a problem on 'WIsH's end of things, but 
	if you replace the above by the equivalent 'AEBuild ...  misc dosc 
	...'  then it is clear the reply is correct.  Therefore Alpha is 
	screwing up somewhere in 'dosc'. 

()	The dialog command (i) fails when given a huge number of items in
	more than 8 panes. (call 'global::allPrefs' to see this happen --
	that's why the prefs have to be subdivided now). (ii) isn't
	documented completely: '-n' option needs explaining.
	
()	Also there's no command to disable an entire menu in one go.
	
()	Furthermore, matchIt fails when matching the '{}' begin and end 'proc'
	pair of a large function.  'balance' works still!  As a concrete
	example, look at proc TeX::Completion::Cite.  matchIt has a built in 
	default of 3000 char max to search.

()	Let 'diff' work on files with Unix eol's as well as just mac ones 
    (it 'works', but treats the entire file as a one line).

()	'dialog' doesn't cope with _very_ complex multi-page dialogs

()  Menu names can't be longer than 24 chars.  Can be problematic
    for filesets menu.  Maximum is now 31 chars (max length of a file
	in MacOS at present).

()	The optional parameter to 'matchIt' doesn't seem to have any effect
	for me.  E.g. the following two procs (when bound to a key) both can
	take up to 10 seconds to return in a large (200k) file.  Presumably the
	first is only supposed to search 200 characters so should be quick.

	proc matchFast {} {
		if ![catch {matchIt ")" [lineStart [getPos]] 200} paren] {
			alertnote "yes"
		} else {	
			alertnote "no"
		}
	}
	proc matchSlow {} {
		if ![catch {matchIt ")" [lineStart [getPos]]} paren] {
			alertnote "yes"
		} else {	
			alertnote "no"
		}
	}

()	The 'time' command reports ticks not microseconds.  Ticks aren't 
	much use (too coarse-grained)

()  The string returned from any 'dialog ....' edit box is not 
	appended to the result correctly.  The result should be a list
	of items, but I guess 'append' rather than 'lappend' is used
	internally.  Example: if a dialog has an edit-item as the
	first item, and I enter '} then {' (to search for obsolete Tcl 
	syntax), the string returned by dialog '{res1 res2 ...}' is 
	actually '{} then { res2 ...}' which is obviously completely
	wrong.  It should have been {{\} then \{} res2 ...}.  Alpha
	should be using 'lappend' internally which will do all the
	hard work of quoting the result for you.  I think the same
	problem occurs with many of Alpha's standard dialogs.
	
()	the '-c' menu option to ignore all meta-characters also ignores all 
	sub-menus (or rather it puts some weird character in the menu and 
	there is no sub-menu).

()  rememberPatternHook is called without quoting its arguments correctly
	This means the call fails if either search of replace string contain
	unquoted '{' or '}'.  (see bug a few lines up for probable solution) 

() 	Add commands/options: (Vince _really_ wants these!)

	'GetTMarks ?-w win?'
	'replaceText ?-w win? ...'
	'getPosOfTMark ?-w win? name'
	
()  'matchIt "\]" $pos' never works --- the ']' argument to matchIt 
	isn't handled correctly; the proc always returns 'no match found'

()	Menu key bindings to items which contain square brackets '[]' do not
	work.  This is because the binding is evaluated, which tries to
	evaluate the '[xxx]'.  When creating the menu item, the text should
	have been surrounded by '{}'.  This is most often manifested in the
	window menu, for which keyboard equivalents cmd-0-9 do not work if
	a window's name contains square brackets.
	(There is a pseudo-workaround for this in the Tcl code).
	Again this is probably a problem with append vs lappend used 
	internally.

()	removeTMark doesn't seem to work

()	Almost none of Alpha's file/glob/cd/... commands support aliases
	This would be fixed with Tcl8.0
	
()	grep, scanfile etc. basically fail on Unix format files: they think
	any match is on the first line of the file.  This is especially
	useless for batch searches in which every match is listed as being
	on the first line.  Upgrading to Tcl 8 should help this!
	
()	icGetPref has some problems (other problems listed below too): 

	Alpha  icGetPref Helperhttp
	lG1MacLynxphervigator 3.0

()	icGetPref on many items returns 'ic err: -670' which is the following 
	error:
	
		icTruncatedErr = -670,	/* more data was present than was returned */
	
	This happens for 'DownloadFolder' for example (_many_ others too).
		
()	posToRowCol doesn't deal with tabs.  Is this a bug or a 
	feature?  Basically on a line beginning with a tab, I'd expect 
	[posToRowCol $start] to be "X 0", and [posToRowCol [incr 
	start]] to be "X 4" (or "X 8" or whatever).  
	
    To put this another way, 'posToRowCol [getPos]' does not have the same
	value as the row/col indicator in the status bar. 
  
()  If you have an untitled dirty window which is not at the front, and then 
	use 'Save all', you will get a save dialog for the window at the front, not 
	the untitled one behind.

()	'regModeKeywords' colorizes keywords without regard to capitalizations, there 
	are plenty of languages where capitalization is significant, it would be 
	nice to have a switch to tell alpha not to ignore keyword capitalization.
	
()	Let 'scanfile' etc.  work on files with Unix eol's as well 
	as just mac ones (they 'work', but treat the entire file as a 
	single line, which isn't too helpful).  Also 'gets' treats an 
	entire file as a single line if it's delimited by '\n'.  I guess
	these issues would be resolved by updating Alpha's Tcl core to 7.6/8.0.

()	Adjusting tab-size/font should not dirty the window.
	(There is a work-around for this in "coreFixes.tcl")
		
()	There are numerous problems (small and large) with Alpha's moveFile
	removeFile etc.  These will go away if Alpha upgrades to Tcl8.0.
	Here's an example: let's say we have files '$a' and '$b' and
	we wish to replace $a with $b.  Then we can't do it.
	
	deleteFile $a ; moveFile $b $a   ;# gives 'unknown error'
	moveFile $a ${a}~ ; moveFile $b $a ; deleteFile ${a}~  ;# gives error

() 	Make the 'listpick' box width & height user configurable?

()	The following line exhibits a bug in the auto-wrap feature of 
	Alpha.  It occurs with any long line which contains no internal
	space but does contain punctuation/braces.  (This actually occurs
	quite frequently in latex 'equation' environments).  Move the 
	cursor to somewhere near the end of the line and start typing (make 
	sure the window isn't read only).  Blank lines are inserted 
	before the given line!	
	
	,asbafsafaskasd.jsasassdkasdas,d{adasdadhja}skasddaasdasasasasasasasaasas
	
()	'puts stderr blah' brings up a SIOUX window and crashes Alpha.  Alpha 
	should be linked with the sioux-stubs, so no sioux-code is linked in,
	and these puts commands should be diverted to some Tcl proc equivalent.
	(the procedure tclLog in "library.tcl" is a good standard alternative)
	Vince can supply you with some C code which will divert stdio to
	given tcl procedures.

()	bringToFront doesn't work on window names which contain colons 
	(unusual case I know)

()	There is no way to get or set the font or font-size of a window from Tcl

()	If a file is opened with a selection (say everything: cmd-A), 
	then closed, and then the data-fork of the file is changed, so 
	that it is shorter, on re-opening the file, the highlighting is 
	v.  odd, and I had to redraw the window to fix it (ctrl-l).  
	Alpha should probably check if highlighting runs past the end of 
	the file.

()	The interaction of the search dialog box with the 'grepfset' procedure
	is incorrect:
 # 
 # "grepfset" --
 # 
 #  args: wordmatch ?-nocase? expression fileset
 #  Obviously we ignore wordmatch
 #  
 #  If the 'Grep' box was set, then the search item is _not_ quoted.
 #  
 #  Non grep searching problems:
 #  
 #  If it wasn't set, then some backslash quoting takes place. 
 #  (The chars: \.+*[]$^ are all quoted)
 #  Unfortunately, this latter case is done incorrectly, so most
 #  non-grep searches which contain a grep-sensitive character fail.
 #  The quoting should use the equivalent of the procedure 'quote::Regfind'
 #  but it doesn't quote () and perhaps other important characters.
 #  
 #  Even worse, if the string contained any '{' it never reaches this
 #  procedure (there must be an internal error due to bad quoting).
 # 

()   Some of them seem to be caused by Alpha not using 
     'lappend' internally when it should be (it often seems to use 'append' 
    together with some inadequate quoting instead).  This causes big 
    problems when characters like '[]{}' are involved.

()	Cmd-double-clicking seems first to check if there is a ':' anywhere in the
	non-whitespace surrounding the click position, and if so sends that text
	off to Internet Config.  Unfortunately if IC doesn't think it is a URL 
	(often the case since, for instance, TeX labels and Tcl procedure names
	may contain colons) the standard 'CmdDblClick' procedure is never called.
	In such a case the cmd-dbl-click is just lost. One way around this is to 
	double-click to get the selection you want, and then invoke the 
	CmdDblClick routine via its keybinding (default = F6).

()	searching backwards for this regexp in a window can lock Alpha up
	or crash with error 28 (stack hits heap):

		(/\*([^*]|[^*]\/|\*[^\/]|\r)*\*/|^\[ \t\]\t*\$)

	Vince can supply a 100% reproducible example of this if needed.
	Minor variants on this regexp have the same problem.  This occurs
	when using text::genericIndent when editing javascript code in
	HTML pages.  I'm not sure what the search is seeing that causes
	the problem.  (text::genericIndent has since been rewritten to
	avoid this trouble). (Will be fixed with new regexp code)

()  'regexp {\w} a' == 1, but 'regexp {[\w]} a' == 0, i.e. the \w only
	matches if it isn't inside a range!  There are many other regexp problems.
	This isn't quite right: regexp {[\w]} a == 0 , but regexp {[\w]+} a == 1.
	Very weird.  (Will be fixed with new regexp code)

()  Regexp's still have some problems:

	Alpha  regsub -all {\W} {aaaaaa  aa} {Z} t
	14
	Alpha  set t
	aaaaaaZZaaZZZtZZZZgZZzZDZZC0Z
	Alpha  
	
    This used to give:
	
	Alpha  regsub -all {\W} {aaaaaa  aa} {Z} t
	7
	Alpha  set t
	aaaaaaZZaaZZZtZZZ
	
    which is also wrong.
	(Will be fixed with new regexp code)

	  	Half-fixed:

()	when dealing with a menu with more than perhaps 20 items, Alpha won't
	unconvert the menu-item when it is sent to the menu-proc.  So if I
	build a menu with 'Menu -n Name -p my_proc {lots of items... thisOne}'
	then 'thisOne' appears in the menu as 'This One' (as desired), but
	when it is selected, the call is 'my_proc Name "This One"' which
	is incorrect.  The menu items near the top of the menu work fine!
	
()	There are many other problems with long menus: 'enableMenuItem'
	doesn't work properly. i.e. enableMenuItem $m thisOne 0 will
	say there's no item with that name, and enableMenuItem $m "This One" 
	0 will not complain, but won't actually disable the item either!
	(Fix only applies with MacOS 8.5 or newer, and ought to work,
	except it seems there's a mercutio problem which means things
	still don't work!)

